<% title 'API Documentation - Libraries.io' %>

<div class="row">
  <div class="col-md-12">
    <h1>API Docs</h1>
  </div>
</div>
<div class="row">
  <div class="col-sm-8">
    <h3 id='authentication'>Authentication</h3>

    <p>
      All API requests must include <code>api_key</code> parameter, get your api key from your
      <%= link_to 'account page', account_path %>
      <% if logged_in? %>
        , all examples on this page include your API key.
      <% end %>
    </p>

    <h3 id='rate-limit'>Rate limit</h3>

    <p>
      All requests are subject to a 60/request/minute rate limit based on your api_key, any further requests within that timeframe will result in a <code>429</code> response.
    </p>

    <h3 id='pagination'>Pagination</h3>

    <p>
      All requests that return multiple results can be paginated using the
      `page` and `per_page` query parameters.
    </p>

    <ul>
      <li><code>page</code> (default is `1`)</li>
      <li><code>per_page</code> (default is `30`, max is `100`)</li>
    </ul>

    <h3 id='platforms'>Platforms</h3>

    <p>
      Get a list of supported package managers.
    </p>

    <p>
      <code>GET https://libraries.io/api/platforms?api_key=<%= @api_key %></code>
    </p>
    <hr>
    <p>
      Example: <strong> <%= link_to nil, "https://libraries.io/api/platforms?api_key=#{@api_key}" %> </strong>
    </p>
    <% cache "api-docs-#{@cache_version}-platforms", :expires_in => 1.day do %>
      <pre class='well well-small'>
<%= JSON.pretty_generate Platform.all.map{|p| PlatformSerializer.new(p) }.as_json %></pre>
    <% end %>


    <h3 id='project'>Project</h3>

    <p>
      Get information about a package and its versions.
    </p>

    <p>
      <code>GET https://libraries.io/api/:platform/:name?api_key=<%= @api_key %></code>
    </p>
    <hr>
    <p>
      Example: <strong> <%= link_to nil, "https://libraries.io/api/#{@project.platform}/#{@project.name}?api_key=#{@api_key}" %> </strong>
    </p>
    <% cache "api-docs-#{@cache_version}-project", :expires_in => 1.day do %>
      <pre class='well well-small'>
<%= JSON.pretty_generate ProjectSerializer.new(@project).as_json %></pre>
    <% end %>
    <h3 id='project-dependencies'>Project Dependencies</h3>

    <p>
      Get a list of dependencies for a version of a project, pass <code>latest</code> to get dependency info for the latest available version
    </p>

    <p>
      <code>GET https://libraries.io/api/:platform/:name/:version/dependencies?api_key=<%= @api_key %></code>
    </p>
    <hr>
    <p>
      Example: <strong> <%= link_to nil, "https://libraries.io/api/#{@project.platform}/#{@project.name}/#{@version.number}/dependencies?api_key=#{@api_key}" %> </strong>
    </p>
    <% cache "api-docs-#{@cache_version}-project-dependencies", :expires_in => 1.day do %>
      <pre class='well well-small'>
<%= JSON.pretty_generate @dependencies %></pre>
    <% end %>
    <h3 id="project-dependents">Project Dependents</h3>

    <p>
      Get packages that have at least one version that depends on a given project.
    </p>



    <p>
      <code>GET https://libraries.io/api/:platform/:name/dependents?api_key=<%= @api_key %></code>
    </p>
    <hr>
    <p>
      Example: <strong> <%= link_to nil, "https://libraries.io/api/#{@project.platform}/#{@project.name}/dependents?api_key=#{@api_key}" %> </strong>
    </p>
    <% cache "api-docs-#{@cache_version}-project-dependents", :expires_in => 1.day do %>
      <pre class='well well-small'>
<%= JSON.pretty_generate @dependent_projects.map{|p| ProjectSerializer.new(p) }.as_json %></pre>
    <% end %>
    <h3 id="project-dependent-repositories">Project Dependent Repositories</h3>

    <p>
      Get repositories that depend on a given project.
    </p>

    <p>
      <code>GET https://libraries.io/api/:platform/:name/dependent_repositories?api_key=<%= @api_key %></code>
    </p>
    <hr>
    <p>
      Example: <strong> <%= link_to nil, "https://libraries.io/api/#{@project.platform}/#{@project.name}/dependent_repositories?api_key=#{@api_key}" %> </strong>
    </p>
    <% cache "api-docs-#{@cache_version}-project-dependent-repositories", :expires_in => 1.day do %>
      <pre class='well well-small'>
<%= JSON.pretty_generate @project.dependent_repositories.paginate(page: 1).as_json(except: [:id, :repository_organisation_id, :repository_user_id], methods: [:github_contributions_count, :github_id]) %></pre>
    <% end %>

    <h3 id="project-contributors">Project Contributors</h3>

    <p>
      Get users that have contributed to a given project.
    </p>

    <p>
      <code>GET https://libraries.io/api/:platform/:name/contributors?api_key=<%= @api_key %></code>
    </p>
    <hr>
    <p>
      Example: <strong> <%= link_to nil, "https://libraries.io/api/#{@project.platform}/#{@project.name}/contributors?api_key=#{@api_key}" %> </strong>
    </p>
    <% cache "api-docs-#{@cache_version}-project-contributors", :expires_in => 1.day do %>
      <pre class='well well-small'>
<%= JSON.pretty_generate @project.contributors.paginate(page: 1).map{|p| RepositoryUserSerializer.new(p) }.as_json %></pre>
    <% end %>

    <h3 id="project-sourcerank">Project SourceRank</h3>

    <p>
      Get breakdown of SourceRank score for a given project.
    </p>

    <p>
      <code>GET https://libraries.io/api/:platform/:name/sourcerank?api_key=<%= @api_key %></code>
    </p>
    <hr>
    <p>
      Example: <strong> <%= link_to nil, "https://libraries.io/api/#{@project.platform}/#{@project.name}/sourcerank?api_key=#{@api_key}" %> </strong>
    </p>
    <% cache "api-docs-#{@cache_version}sourcerank", :expires_in => 1.day do %>
      <pre class='well well-small'>
<%= JSON.pretty_generate @project.source_rank_breakdown.as_json %></pre>
    <% end %>

    <h3 id="project-search">Project Search</h3>

    <p>
      Search for projects
    </p>

    <p>
      <code>GET https://libraries.io/api/search?q=grunt&api_key=<%= @api_key %></code>
    </p>
    <hr>
    <p>
      The search endpoint accepts a <code>sort</code> parameter, one of
        <code>rank</code>,
        <code>stars</code>,
        <code>dependents_count</code>,
        <code>dependent_repos_count</code>,
        <code>latest_release_published_at</code>,
        <code>contributions_count</code>,
        <code>created_at</code>.
    </p>
    <hr>
    <p>
      The search endpoint accepts number of other parameters to filter results:
    </p>
    <ul>
      <li><code>languages</code></li>
      <li><code>licenses</code></li>
      <li><code>keywords</code></li>
      <li><code>platforms</code></li>
    </ul>
    <hr>
    <p>
      Example: <strong> <%= link_to nil, "https://libraries.io/api/search?q=grunt&api_key=#{@api_key}" %> </strong>
    </p>
    <% cache "api-docs-#{@cache_version}-project-search", :expires_in => 1.day do %>
      <pre class='well well-small'>
<%= JSON.pretty_generate @search.map{|p| ProjectSerializer.new(p) }.as_json %></pre>
    <% end %>
    <h3 id='repository'>Repository</h3>

    <p>
      Get info for a repository. Currently only works for open source repositories.
    </p>
    <p>
      <code>GET https://libraries.io/api/github/:owner/:name?api_key=<%= @api_key %></code>
    </p>
    <hr>
    <p>
      Example: <strong> <%= link_to nil, "https://libraries.io/api/github/#{@repository.full_name}?api_key=#{@api_key}" %> </strong>
    </p>
    <% cache "api-docs-#{@cache_version}-repository", :expires_in => 1.day do %>
      <pre class='well well-small'>
<%= JSON.pretty_generate @repository.as_json({except: [:id, :repository_organisation_id, :repository_user_id], methods: [:github_contributions_count, :github_id]}) %></pre>
    <% end %>
    <h3 id='repository-dependencies'>Repository Dependencies</h3>

    <p>
      Get a list of dependencies for a repositories. Currently only works for open source repositories.
    </p>
    <p>
      <code>GET https://libraries.io/api/github/:owner/:name/dependencies?api_key=<%= @api_key %></code>
    </p>
    <hr>
    <p>
      Example: <strong> <%= link_to nil, "https://libraries.io/api/github/#{@repository.full_name}/dependencies?api_key=#{@api_key}" %> </strong>
    </p>
    <% cache "api-docs-#{@cache_version}-repository-dependencies", :expires_in => 1.day do %>
      <pre class='well well-small'>
<%= JSON.pretty_generate @repo_dependencies %></pre>
    <% end %>
    <h3 id="repository-projects">Repository Projects</h3>

    <p>
      Get a list of packages referencing the given repository.
    </p>
    <p>
      <code>GET https://libraries.io/api/github/:owner/:name/projects?api_key=<%= @api_key %></code>
    </p>
    <hr>
    <p>
      Example: <strong> <%= link_to nil, "https://libraries.io/api/github/#{@repository.full_name}/projects?api_key=#{@api_key}" %> </strong>
    </p>
    <% cache "api-docs-#{@cache_version}-repository-projects", :expires_in => 1.day do %>
      <pre class='well well-small'>
<%= JSON.pretty_generate @repository.projects.includes(:versions, :repository).paginate(page: 1).map{|p| ProjectSerializer.new(p) }.as_json %></pre>
    <% end %>

    <h3 id='user'>User</h3>
    <p>
      Get information for a given user or organization.
    </p>
    <p>
      <code>GET https://libraries.io/api/github/:login?api_key=<%= @api_key %></code>
    </p>
    <hr>
    <p>
      Example: <strong><%= link_to nil, "https://libraries.io/api/github/#{@repository_user.login}?api_key=#{@api_key}" %></strong>
    </p>
    <% cache "api-docs-#{@cache_version}-user", :expires_in => 1.day do %>
      <pre class='well well-small'>
<%= JSON.pretty_generate @repository_user.as_json %></pre>
    <% end %>

    <h3 id="user-repositories">User Repositories</h3>

    <p>
      Get repositories owned by a user.
    </p>

    <p>
      <code>GET https://libraries.io/api/github/:login/repositories?api_key=<%= @api_key %></code>
    </p>
    <hr>
    <p>
      Example: <strong> <%= link_to nil, "https://libraries.io/api/github/librariesio/repositories?api_key=#{@api_key}" %> </strong>
    </p>
    <% cache "api-docs-#{@cache_version}-github-user-repositories", :expires_in => 1.day do %>
      <pre class='well well-small'>
<%= JSON.pretty_generate @repository_user.open_source_repositories.paginate(page: 1).as_json(except: [:id, :repository_organisation_id, :repository_user_id], methods: [:github_contributions_count, :github_id]) %></pre>
    <% end %>

    <h3 id="user-projects">User Packages</h3>

    <p>
      Get a list of packages referencing the given user's repositories.
    </p>

    <p>
      <code>GET https://libraries.io/api/github/:login/projects?api_key=<%= @api_key %></code>
    </p>
    <hr>
    <p>
      Example: <strong> <%= link_to nil, "https://libraries.io/api/github/#{@repository_user.login}/projects?api_key=#{@api_key}" %> </strong>
    </p>
    <% cache "api-docs-#{@cache_version}-github-user-projects", :expires_in => 1.day do %>
      <pre class='well well-small'>
<%= JSON.pretty_generate @repository_user.projects.includes(:versions, :repository).paginate(page: 1).map{|p| ProjectSerializer.new(p) }.as_json %></pre>
    <% end %>

    <h3 id="user-project-contributions">User Packages Contributions</h3>

    <p>
      Get a list of packages that the given user has contributed to.
    </p>

    <p>
      <code>GET https://libraries.io/api/github/:login/project-contributions?api_key=<%= @api_key %></code>
    </p>
    <hr>
    <p>
      Example: <strong> <%= link_to nil, "https://libraries.io/api/github/#{@repository_user.login}/project-contributions?api_key=#{@api_key}" %> </strong>
    </p>
    <% cache "api-docs-#{@cache_version}-github-user-project-contributions", :expires_in => 1.day do %>
      <pre class='well well-small'>
<%= JSON.pretty_generate @repository_user.contributed_projects.includes(:versions, :repository).order('rank DESC NULLS LAST').paginate(page: 1).map{|p| ProjectSerializer.new(p) }.as_json %></pre>
    <% end %>

    <h3 id="user-repository-contributions">User Repository Contributions</h3>

    <p>
      Get a list of repositories that the given user has contributed to.
    </p>

    <p>
      <code>GET https://libraries.io/api/github/:login/repository-contributions?api_key=<%= @api_key %></code>
    </p>
    <hr>
    <p>
      Example: <strong> <%= link_to nil, "https://libraries.io/api/github/#{@repository_user.login}/repository-contributions?api_key=#{@api_key}" %> </strong>
    </p>
    <% cache "api-docs-#{@cache_version}-github-user-repository-contributions", :expires_in => 1.day do %>
      <pre class='well well-small'>
<%= JSON.pretty_generate @repository_user.contributed_repositories.order('stargazers_count DESC, rank DESC NULLS LAST').paginate(page: 1).map{|p| RepositorySerializer.new(p) }.as_json %></pre>
    <% end %>

    <h3 id="user-dependencies">User Dependencies</h3>

    <p>
      Get a list of unique packages that the given user's repositories list as a dependency. Ordered by frequency of use in those repositories.
    </p>
    <p>
      Parameters: <code>platform</code>
    </p>
    <p>
      <code>GET https://libraries.io/api/github/:login/dependencies?api_key=<%= @api_key %></code>
    </p>
    <hr>
    <p>
      Example: <strong> <%= link_to nil, "https://libraries.io/api/github/#{@repository_user.login}/dependencies?api_key=#{@api_key}" %> </strong>
    </p>
    <% cache "api-docs-#{@cache_version}-github-user-dependencies", :expires_in => 1.day do %>
      <pre class='well well-small'>
<%= JSON.pretty_generate @repository_user.favourite_projects.visible.paginate(page: 1).map{|p| ProjectSerializer.new(p) }.as_json %></pre>
    <% end %>

    <h3 id='subscriptions-index'>User Subscriptions</h3>
    <p>
      List packages that a user is subscribed to receive notifications about new releases.
    </p>

    <p>
      <code>GET https://libraries.io/api/subscriptions?api_key=<%= @api_key %></code>
    </p>
    <hr>
    <p>
      Example: <strong> <%= link_to nil, "https://libraries.io/api/subscriptions?api_key=#{@api_key}" %> </strong>
    </p>
    <% cache "api-docs-#{@cache_version}-subscriptions-index", :expires_in => 1.day do %>
      <pre class='well well-small'>
<%= JSON.pretty_generate Subscription.limit(2).as_json(only: [:include_prerelease, :created_at, :updated_at], include: {project: {methods: [:package_manager_url, :stars, :forks, :keywords, :latest_stable_release], include: {versions: {only: [:number, :published_at]} }}}) %></pre>
    <% end %>

    <h3 id='subscriptions-create'>Subscribe to a project</h3>
    <p>
      Subscribe to receive notifications about new releases of a project.
    </p>
    <p>
      Parameters: <code>include_prerelease</code>
    </p>
    <p>
      <code>POST https://libraries.io/api/subscriptions/:platform/:name?api_key=<%= @api_key %></code>
    </p>
    <hr>
    <p>
      Example: <strong> <%= link_to nil, "https://libraries.io/api/subscriptions/#{@project.platform}/#{@project.name}?api_key=#{@api_key}" %> </strong>
    </p>
    <% cache "api-docs-#{@cache_version}-subscriptions-create", :expires_in => 1.day do %>
      <pre class='well well-small'>
<%= JSON.pretty_generate Subscription.first.as_json(only: [:include_prerelease, :created_at, :updated_at], include: {project: {methods: [:package_manager_url, :stars, :forks, :keywords, :latest_stable_release], include: {versions: {only: [:number, :published_at]} }}}) %></pre>
    <% end %>

    <h3 id='subscriptions-show'>Check if subscribed to a project</h3>
    <p>
      Check if a users is subscribed to receive notifications about new releases of a project.
    </p>
    <p>
      <code>GET https://libraries.io/api/subscriptions/:platform/:name?api_key=<%= @api_key %></code>
    </p>
    <hr>
    <p>
      Example: <strong> <%= link_to nil, "https://libraries.io/api/subscriptions/#{@project.platform}/#{@project.name}?api_key=#{@api_key}" %> </strong>
    </p>
    <% cache "api-docs-#{@cache_version}-subscriptions-show", :expires_in => 1.day do %>
      <pre class='well well-small'>
<%= JSON.pretty_generate Subscription.first.as_json(only: [:include_prerelease, :created_at, :updated_at], include: {project: {methods: [:package_manager_url, :stars, :forks, :keywords, :latest_stable_release], include: {versions: {only: [:number, :published_at]} }}}) %></pre>
    <% end %>

    <h3 id='subscriptions-update'>Update a subscription</h3>
    <p>
      Update the options for a subscription
    </p>
    <p>
      Parameters: <code>include_prerelease</code>
    </p>
    <p>
      <code>PUT https://libraries.io/api/subscriptions/:platform/:name?api_key=<%= @api_key %></code>
    </p>
    <hr>
    <p>
      Example: <strong> <%= link_to nil, "https://libraries.io/api/subscriptions/#{@project.platform}/#{@project.name}?api_key=#{@api_key}" %> </strong>
    </p>
    <% cache "api-docs-#{@cache_version}-subscriptions-update", :expires_in => 1.day do %>
      <pre class='well well-small'>
    <%= JSON.pretty_generate Subscription.first.as_json(only: [:include_prerelease, :created_at, :updated_at], include: {project: {methods: [:package_manager_url, :stars, :forks, :keywords, :latest_stable_release], include: {versions: {only: [:number, :published_at]} }}}) %></pre>
    <% end %>

    <h3 id='subscriptions-destroy'>Unsubscribe from a project</h3>
    <p>
      Stop receiving release notifications from a project.
    </p>
    <p>
      <code>DELETE https://libraries.io/api/subscriptions/:platform/:name?api_key=<%= @api_key %></code>
    </p>
    <hr>
    <p>
      Example: <strong> <%= link_to nil, "https://libraries.io/api/subscriptions/#{@project.platform}/#{@project.name}?api_key=#{@api_key}" %> </strong>
    </p>
    <hr>
    <h3 id='api-wrappers'>API Wrappers</h3>
    <p>
      JavaScript / Node
    </p>
    <ul>
      <li><a href="https://libraries.io/npm/librarian-api">librarian-api</a></li>
    </ul>
    <ul>
      <li><a href="https://libraries.io/npm/libraries.io">libraries.io</a></li>
    </ul>
    <p>
      Python
    </p>
    <ul>
      <li><a href="https://pypi.org/project/pybraries/">pybraries</a></li>
    </ul>
    <p>
      Go
    </p>
    <ul>
      <li><a href="https://github.com/hackebrot/go-librariesio">go-librariesio</a></li>
    </ul>
    <p>
      R
    </p>
    <ul>
      <li><a href="https://github.com/ropenscilabs/rbraries">rbraries</a></li>
    </ul>
    <p>
      Ruby
    </p>
    <ul>
      <li><a href="https://github.com/marcandre/libraries_io">libraries_io</a></li>
    </ul>

  </div>
  <div class="col-sm-4">
    <h3>API Methods</h3>
    <ul>
      <li><a href="#authentication">Authentication</a></li>
      <li><a href="#rate-limit">Rate limit</a></li>
      <li><a href="#pagination">Pagination</a></li>
    </ul>
    <ul>
      <li><a href="#platforms">Platforms</a></li>
    </ul>
    <ul>
      <li><a href="#project">Project</a></li>
      <li><a href="#project-dependencies">Project Dependencies</a></li>
      <li><a href="#project-dependents">Project Dependents</a></li>
      <li><a href="#project-dependent-repositories">Project Dependent Repositories</a></li>
      <li><a href="#project-contributors">Project Contributors</a></li>
      <li><a href="#project-sourcerank">Project SourceRank</a></li>
      <li><a href="#project-search">Project Search</a></li>
    </ul>
    <ul>
      <li><a href="#repository">Repository</a></li>
      <li><a href="#repository-dependencies">Repository Dependencies</a></li>
      <li><a href="#repository-projects">Repository Projects</a></li>
    </ul>
    <ul>
      <li><a href="#user">User</a></li>
      <li><a href="#user-repositories">User Repositories</a></li>
      <li><a href="#user-projects">User Projects</a></li>
      <li><a href="#user-project-contributions">User Package Contributions</a></li>
      <li><a href="#user-repository-contributions">User Repository Contributions</a></li>
      <li><a href="#user-dependencies">User Dependencies</a></li>
    </ul>
    <ul>
      <li><a href="#subscriptions-index">User Subscriptions</a></li>
      <li><a href="#subscriptions-create">Subscribe to a project</a></li>
      <li><a href="#subscriptions-show">Check if subscribed to a project</a></li>
      <li><a href="#subscriptions-update">Update a subscription</a></li>
      <li><a href="#subscriptions-destroy">Unsubscribe from a project</a></li>
    </ul>
    <ul>
      <li><a href="#api-wrappers">Wrappers</a></li>
    </ul>
    <p>
      For any questions, feature requests or bug reports<br/>
      email <%= mail_to 'support@libraries.io', 'support@libraries.io', subject: 'Libraries.io API' %> or
      <%= link_to 'open an issue', 'https://github.com/librariesio/libraries.io/issues/new' %>.
    </p>
  </div>
</div>
